001 /*
002 * Copyright 2004 Niclas Hedhman.
003 * Copyright 2005 Stephen McConnell
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.
015 *
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019
020 package net.dpml.transit;
021
022 import java.io.InputStream;
023 import java.io.OutputStream;
024 import java.io.IOException;
025
026 import java.net.URL;
027
028 import java.util.Date;
029
030 /**
031 * An interface that represents locations where the artifacts can be
032 * downloaded.
033 *
034 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
035 * @version 1.0.1
036 */
037 public interface ResourceHost
038 {
039 /** Downloads the given artifact to the directory indicated.
040 * <p>
041 * The cachedir argument is the root cache directory, and the ResourceHost
042 * class is responsible for the creation of the directory structure of the
043 * group if nonexistent.
044 * </p>
045 * <p>
046 * If the knownOnly argument is true, then only attempt download if the
047 * group is known to exist on this resource host.
048 * </p>
049 * @param artifact the artifact that is requested to be downloaded.
050 * @param dest The output stream where to write the downloaded content.
051 * @exception IOException if an IO related error occurs
052 * @return the lastModified date of the downloaded artifact.
053 */
054 Date download( Artifact artifact, OutputStream dest )
055 throws IOException;
056
057 /** Uploads the given file to the resource host as an artifact.
058 *
059 * @param artifact the artifact destination specification.
060 * @param source The input stream from where to read the content to be uploaded.
061 * @exception IOException if an IO related error occurs
062 */
063 void upload( Artifact artifact, InputStream source )
064 throws IOException;
065
066 /** Checks if the Artifact is present on the resource host.
067 *
068 * <p>
069 * Performs a check to see if the artifact exists on the resource host. If
070 * <i>knownOnly</i> is set to true, then the implementation will only
071 * consult the knownGroups table, and if found there, it is considered
072 * found without checking at the resource host itself. If <i>knownOnly</i>
073 * is false, however, a connection will be established to the resource
074 * host and a check of the actual resource existence.
075 * </p>
076 *
077 * @param artifact the artifact for which the method checks its presence.
078 * @param knownOnly does not perform a remote connection, and instead lookup
079 * the group table, and if not found there it will return false.
080 *
081 * @return true if the artifact can be located, false otherwise.
082 */
083 boolean checkPresence( Artifact artifact, boolean knownOnly );
084
085 /** Returns the hostname of the resource host.
086 *
087 * <p>
088 * This does not include any of the path, but does include any port number
089 * of this resource host.
090 * </p>
091 * @return the hostname
092 */
093 String getHostName();
094
095 /**
096 * Returns the full host url.
097 *
098 * @return the host url
099 */
100 URL getURL();
101
102 /**
103 * Return true if the resource host has been enabled.
104 *
105 * @return true if the resource host is enabled, false if not.
106 */
107 boolean isEnabled();
108
109 /** Returns true if the ResourceHost is considered trusted.
110 * @return true if the host is trusted
111 */
112 boolean isTrusted();
113
114 /** Returns the priority of the resource host.
115 *
116 * A high number indicates a more important host that should take precendence
117 * over a host with lower number.
118 * @return the host priority
119 */
120 int getPriority();
121 }